Using the Object.watch method in Macromedia Flash MX

Issue
the Object.watch method's callback function returns "undefined" where a value is expected.

Reason
The original ActionScript Dictionary entry for Object.watch is incorrect. The correct definition is described in ActionScript Dictionary Errata and is correct in the online Object.watch definition. The correct entry is also available in the latest documentation update. See Macromedia Flash MX Documentation Update (TechNote 16470) for details.

To work correctly, the callback function must specify the 'newval' argument.

An example of a commonly made mistake:

myObject = {name:"John", age: 26};
trace(myObject.watch("age",myBirthday));

function myBirthday(){        //note missing arguments
 trace("My Name is " + myObject.name);
 trace("It's my birthday today!");
}
myObject.age++;
trace("I'm " + myObject.age + " years old!");
trace(myObject.age);

The expected result is that the last trace statement will return a value of 27, however, "undefined" is returned in the output window.

Solution
When using the Object.watch method, remember to 'return' the new value from the callback function, otherwise the value is undefined.

Modify the code as follows to return the correct value:

myObject = {name:"John", age: 26};
trace(myObject.watch("age",myBirthday));

function myBirthday(property,oldval,newval){  //correct arguments
 trace("My Name is " + myObject.name);
 trace("It's my birthday today!");
 return newval;
}
myObject.age++;
trace("I'm " + myObject.age + " years old!");
trace(myObject.age);